home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software of the Month Club 1998 June
/
Software of the Month Club 1998 June.iso
/
pc
/
dos
/
lg
/
vde
/
vmacro.ref
< prev
next >
Wrap
Text File
|
1998-04-15
|
47KB
|
817 lines
VMACRO.REF
----------
Macro Reference for the VDE Editor:
version 1.85 (21 Jan 1998)
(c)1987-98, E. Meyer
=============================== CONTENTS ==================================
9. CREATING MACROS:
A. Keystrokes and notation
B. Defining macros
C. Recording macros
D. Assigning macros to keys
E. Macro programming
F. Examples of useful macros
G. Adding features: Mail Merge
10. MACRO REFERENCE, alphabetically by topic:
Autoexec macro, Chaining and calling, Counter variable, Define or
record macro, Error handling, Function keys, Function key labels,
Key definition files, Labels and jumps, Pause or user input, Prompt
automation, Sorting, Tests and loops, Toggle control, Value
adjustment.
See also:
VDE.DOC - QUICK START, SYNTAX, TECHNICAL INFORMATION, etc.
VDE.REF - comprehensive COMMAND REFERENCE
VINST.REF - use of the VINST installation utility
========================== 9. CREATING MACROS =============================
A. KEYSTROKES AND NOTATION
Essentially, a macro is a sequence of keystrokes representing text and/or
VDE commands, which can then be repeated automatically or stored to a key for
future use in order to make frequently performed tasks easier.
While this may sound quite straightforward, it's obviously necessary to
get such a key sequence EXACTLY correct for the macro to perform as intended;
therefore, the representations of macros in this manual present many
possibilities for confusion. First, some basics: the characters "[]" are
often used to signify the pressing of a single key, like "[Esc]" -- but they
aren't used when that key is exhibited as part of a macro or multi-key
command, like "Esc&F2". Also, don't be confused by the fact that a single
bracket can also appear as part of certain macro commands, like "Esc~^M]".
The character "^" is normally used to indicate control-key combinations, as
in "^M" for Ctrl-M; but there are special cases when the character "^" itself
needs to be typed, as in "Esc&^F2" or "^K^".
A space will often be used here to separate groups of keystrokes to make
a macro easier to read and understand -- but these spaces ARE NOT part of the
macro, and should not be typed in when trying to define it. Any spaces that
actually ARE part of the macro and SHOULD be typed in are represented by the
underline character "_", which is not itself part of any macro here.
Finally, there are occasional differences between the keystrokes you
would actually type in order to perform a task, and those that must be typed
in order to enter this sequence at the macro definition prompt. At all VDE
string prompts, certain keys control the entering of the string itself; for
the macro definition command ^M, this is a somewhat shorter list than for
other PROMPTS, but it still includes:
[Enter], ^[Enter] -- macro definition complete
[<],[>],[BkSp],[Del] -- correct/edit characters entered
^R -- (as 1st key) replay the last macro entered
^P -- enter codes like these in macro
This means that to include any of these keys AS PART OF THE MACRO ITSELF
requires the ^P prefix first (except for [>] and [Del] when the cursor is at
the end of the input line). If you forget this prefix, of course, the key
will instead perform its function indicated above.
Throughout this manual, macros are presented as they actually function,
since this is easier to understand; that is, they DO NOT include any extra ^P
prefixes required for code entry. If you're trying to enter a macro at the
definition prompt, you must remember to use caution with the above control
keys! (See also ^P NESTING, below.)
It is also important to bear in mind that starting with VDE 1.8, the
following keys are no longer equivalent for most purposes:
[Enter] and ^M (CR) [BkSp] and ^H [Esc] and ^[
^[Enter] and ^J (LF) [Tab] and ^I
The one case where these keys remain interchangeable is in their use after ^P
to embed an ASCII control-code (like ^H, ASCII 08) in the text. Otherwise,
they are related but distinct: [BkSp] is a COMMAND that deletes a character
from the text or a prompt input line, while ^H (BS) is a CHARACTER that can
be part of the text (where it will cause a backspace when printing); ^H can
also be an entirely unrelated COMMAND itself. [BkSp] will require a ^P
prefix to enter into a macro, ^H will not; and so on. (Any macros from VDE
versions prior to 1.8 will need to be redefined with these differences in
mind.)
EXAMPLE: Consider the following macro, whose purpose is explained more
fully below under EXAMPLES OF USEFUL MACROS:
^QS ^X Esc=_] Esc=^M] ^S_^D Esc![
Following the explanations above, be sure you understand why in the middle of
defining this macro you must use ^M, not [Enter], and verify that it will
involve 17 separate keystrokes, namely:
Macro: Ctrl-Q S Ctrl-X Esc = Space ] Esc = Ctrl-M ]
Ctrl-S Space Ctrl-D Esc ! [
and then, of course, a final [Enter] to terminate the definition. If you do
this correctly, you'll see on screen something like this (the underlined
letters will be highlighted as control-codes, and the "e" symbol indicating
the [Esc] key is actually an epsilon):
Macro: QSXe= ]e=M]S De![
- -- - - - --
---------------------------- B. DEFINING MACROS -----------------------------
To DEFINE a Macro, press ^M. Macros execute EXACTLY as though you had
typed the given keys yourself; this means that every keystroke, including
answers to prompts, [Enter]s, and so on, must be properly included, so plan
ahead carefully, with pen and paper if necessary.
Any PC keys can be entered at this prompt; a few, like arrow keys, will
display with a recognizable symbol, but most (PgUp, etc) will simply show as
a highlighted asterisk "*". (VINST is capable of displaying the full
keynames, if you create or display macros with it instead.) Even MenuBar
selections (except {User:...}) can be used in macros, with the ^[Esc] command
(see MENUBARS).
Since the macro prompt accepts [Esc] without a ^P-prefix, it can't be
used to abandon the definition; you can only do so by pressing ^[Break], or
[Enter] followed by [Esc] at the next prompt.
You can end a macro definition by pressing ^[Enter], to bypass the
options below: VDE will simply repeat your macro (visibly) until you press
[Esc] to stop it. Otherwise, if you press [Enter], VDE will ask whether you
want to Use it immediately or store it (on storing, see ASSIGNING MACROS TO
KEYS). If you're going to use it now, you need to decide whether you want
the macro to repeat (and if so, how many times), and whether you want to
watch it happen.
VDE asks "Make Quiet, No-repeat, Both?" Reply "Q" for
Quiet (fast) operation, or press [Enter] for visible
(slower) execution. (The "N/B" options are intended for
storing to keys, but can also be typed here to skip the
next question.)
VDE asks "Repeat count?" Type the number of times to
execute (0-254), or just [Enter] for 1; or "*" to repeat
indefinitely.
When a macro is executing, the "!" flag appears in the header; normally,
you can also see its effects as it proceeds. You can cancel it at any time
by pressing [Esc]. If you chose to speed up macro execution by specifying
"Q"uiet mode, only the header will be updated as the macro runs. (Don't do
this if the macro uses any commands that require user input -- the necessary
prompt would not display, and the macro would just appear to have stalled.)
By default, macros will stop automatically if an error condition occurs,
in which case the error message will display briefly; or if the cursor
attempts to move past the top or end of the file, in which case no error
displays. (See also ERROR HANDLING.) Thus some macros will halt on their
own when they reach the end of a file; others may have to be terminated
manually, by pressing [Esc].
Once defined, a macro can be recovered by typing ^R to replay it at the
^M prompt, so that you can choose to Use it again, or store it if you did not
previously do so. (You can also edit it first, if desired.)
^F, when entered as part of an input string, normally inserts the name of
the current file (see PROMPTS). In a macro definition, it remains an ^F,
expanded to the current filename only when the macro actually executes. This
can be useful to refer to the current file when running compilers and file
utilities. Thus, if you define the macro
AltR compile_^F_/g_/r1 [Enter] [Esc]
the ^F embedded in the string will be expanded, so that the DOS command
executed by AltR when the macro is invoked will actually be something like
compile C:\PGM\MYPROG.C /g /r1.
Note: if the file is untitled, ^F causes an error that halts the macro.
Similarly, ^[, which inserts text from a block at a prompt, remains ^[ in
a macro definition, inserting the block text only when the macro actually
executes. This useful feature makes it possible for a macro to search for
further occurrences of whatever text is at the cursor, etc.
EXAMPLES OF ^P NESTING. Note that in some situations, the use of ^P as a
prefix for control keys at the macro definition prompt becomes nested.
Suppose you want to define a macro containing the word "counterrevolutionary"
with "counter" italicized. The keystrokes you'd use yourself are:
^P^Ycounter^P^Yrevolutionary
but to get these into a macro definition, you must type ^P TWICE to enter
each ^P; ^P^Y by itself will enter only the ^Y into the macro, which would
delete a line! So you'll type:
Macro: ...^PP^Ycounter^PP^Yrevolutionary...
Or, suppose you want to find the next occurrence of "Item" at the
beginning of a line. The actual keystrokes needed are:
^QF^MItem^[Enter]
(Note the use of ^[Enter] instead of [Enter] to avoid the Options prompt.)
But to enter this as part of a macro definition, you'll have to type:
Macro: ...^QF^MItem^P^[Enter]...
Failure to nest ^P prefixes properly is one of the most common causes of
unexpected macro behavior.
TECHNICAL NOTE: Ordinarily macros are completely self-contained, and
NEVER request input from the keyboard while executing (unless the input pause
commands Esc? or Esc: are used). Confirmation prompts like "Abandon changes
(Y/N)?", which may or may not pop up in normal usage of commands affecting
disk files, NEVER occur when a macro is running, so you should never try to
include a confirming "Y". But there is one exception: using AltR to run
another program (or DOS shell) from a macro is tricky. Any input requested
by the program or shell must be typed by you -- it cannot be included in the
macro. VDE resumes control only when the program or shell terminates; if the
macro continues, its next keystroke must be the [Esc] required to return to
editing.
--------------------------- C. RECORDING MACROS -----------------------------
As an alternative to composing macros and using the ^M command to define
them, you can simply record a macro as you go about a task. The main
advantages are that you can see the effects as you go, and none of the
additional ^P keystrokes sometimes necessary for entering commands at the
macro definition prompt will be needed. (On the other hand, a recorded macro
must be a simple series of keystrokes; it cannot contain programming commands
like jumps and tests.)
Just press ^M^M (that is, ^M again at the Macro prompt) to activate
recording; type away; and press ^M again to conclude. You will then be asked
whether to use or store the macro you have created, just as if you had
entered the macro at the prompt. (You can even recall it with ^R the next
time you use the ^M command.)
While recording, a quote mark (") will be visible in the upper right
(prefix) area of the header. If you make a mistake, use ^M again to stop
recording, press [Esc] at the prompt to quit, and start over. If anything
you do while recording results in an error condition, recording will be
canceled, and the quote will disappear from the header.
NOTES: Because Function key commands (and also the {User:} MenuBar) use
the same internal processes as macros, they cannot be used while macro
recording is in progress. Any other keystrokes can be recorded, including
all other MenuBar selections. Although they may not always be usefully
precise, even mouse movements can be recorded as part of a macro, because
they are simulated internally as sequences of arrow keys.
----------------------- D. ASSIGNING MACROS TO KEYS -------------------------
Macros can be assigned to function keys, and then recalled and used with
one keystroke. Each PC function key can be used alone or with Shift (often
indicated by VDE as "!"), Ctrl ("^"), or Alt ("@"), to produce 48 different
macro keys. VDE comes with [F1] set as "Help" (^J) and [F10] as "Menu"
(^Esc), but this can be changed.
If you find function keys difficult to remember, you can also assign a
mnemonic letter or digit (alias) to invoke a definition with the [Esc] key;
thus, if your Address is on ^[F3], you could also call it up with EscA.
The ^M command (see MACRO DEFINITION) gives the option of storing the
macro definition to any function key, so that the macro can later be executed
simply by pressing that key. Instead of selecting "U"se, press the desired
key, from [F1] to @[F12]. Then:
VDE asks "Make Quiet, No-repeat, Both:". Reply "Q" for
a key that executes in Quiet (fast) mode; "N" for a key
that runs once, without asking for a repeat count; or "B"
for both of these. Just press [Enter] for neither -- a key
that executes just like the "Use" option, visibly, asking
for a repeat count first.
VDE asks "Esc key:". If desired, you can choose a
letter or digit to press after [Esc] as an alternate way of
invoking this macro.
VDE asks "Label?". You may enter a label, up to 7
characters, for the label line (see FUNCTION KEY LABELS).
Don't choose "Q"uiet (or "B"oth) for a key that will request input from
you. About 2000 bytes of storage are available for all 48 keys, and a 125-
byte limit applies [in VDE; VINST can accept 253] to any one key. You can
delete an existing key definition by entering a null definition (^M, [Enter])
and storing it to the key.
Keys defined while editing in VDE last only during the current editing
session. [To add a function key permanently to VDE.EXE, use VINST: either
enter it again in VINST, or write it to a file and read the file into VINST
-- see DEFAULT FUNCTION KEYS and DATA FILES.]
--------------------------- E. MACRO PROGRAMMING ----------------------------
"Macro programming" refers to a group of VDE commands that operate only
within a macro definition, and give you conditional control over the
execution of a macro. Thus, instead of simply running straight through a
sequence of keystrokes, a macro can be constructed very much like a computer
program, with conditional or unconditional jumps from one part of the macro
to another, giving great flexibility and power. Here is a brief introduction
to the range of macro programming commands.
Jumps require "labels" to identify a location to jump to: a macro label
consists of [Esc] followed by a letter A-Z or digit 0-9. If you typed this
from the keyboard, it would be interpreted as an attempt to invoke a function
key definition by an alias (see FUNCTION KEYS) -- but a macro can't do this,
so EscA simply marks a location in the macro.
Esc! is the unconditional jump instruction. Followed by A-Z or 0-9, it
causes execution of the macro to transfer to the command following that
label, instead of simply continuing as usual to the next command. So, for
example, Esc!1 jumps to the label Esc1. Thus the macro:
This_is_ Esc!1 not_ Esc1 a_silly_macro.
would produce the text "This is a silly macro." In contrast, the macro:
This_is_ Esc1 not_ Esc!1 a_silly_macro.
would produce "This is not not not not not not not not not....", continuing
indefinitely until you press [Esc] to abort it. (This is an example of what
programmers call an "infinite loop" -- occasionally useful, but generally an
unfortunate error!)
There are also two special predefined "labels": "[" indicates the
beginning of the macro, and "]" the end. Thus Esc![ can be used to repeat
the macro from the start, and Esc!] can be used to terminate it from any
point.
Several commands allow the use of a counter variable. Esc() sets the
value: for example, Esc(0) initializes it to zero. The Esc+ command simply
increments the value; Esc- (minus) is a conditional jump, decrementing the
value, then jumping if it's zero to the specified label. (In addition to a
label 0-Z, you may use "[" or "]", or "@" to avoid jumping entirely.)
Examples: Esc-] decrements the counter, jumping to the end (exiting) if it
reaches zero; Esc-@ simply decrements it, with no jump. Thus the macro:
This_is_a_ Esc(3) EscL silly_ Esc-X Esc!L EscX macro.
will produce the text "This is a silly silly silly macro."
Conditional jumps, or tests, are performed by Esc= and Esc~. Followed by
a character, then a label, they are conditional jumps: they jump IF the text
character at the cursor does (or for "~", does NOT) match the one specified.
Examples: Esc~_2 jumps to label 2 if the cursor character is NOT a space;
Esc=^M] jumps to the end (terminates) if the cursor character is a CR (^M).
Similarly, Esc< and Esc> test the cursor character's ASCII value and act
accordingly: thus Esc<A2 jumps to label 2 if the cursor character value is
less than ASCII "A" (41 hex), etc.
The test commands (Esc=,~,<,>) can also be used in a second way, as self-
contained search loops. If instead of a label you use the character ">" or
"<", the command will move the cursor right (or for "<", left) as long as the
character at the cursor does (or for "~", does NOT) match the one specified.
Example: Esc=_> moves right as long as the current character is a space (so
it stops on the first NONspace). Of course you could have done the same
thing by programming an actual loop, with labels and a test and a right arrow
command:
Esc1 Esc~_2 ^D Esc!1 Esc2
but Esc=_> is simpler and more convenient.
It is possible for one macro to chain (jump) to, or call, another macro.
This can permit construction of a single macro longer than the usual maximum
size; also, it often simply allows you to organize macros more efficiently
and conserve definition space. Esc&, followed by a key identification like
"!F1", is used to chain to another key; the macro terminates when that key
finishes. Esc&& works similarly, but calls the other key, so that when it
finishes, control returns to the original macro at the point following the
Esc&& command.
----------------------- F. EXAMPLES OF USEFUL MACROS ------------------------
Remember that macro examples are given as they function, NOT including
the occasional ^P prefix you'll need to enter certain keys; and that while
keystrokes are often separated by spaces for clarity, the underline symbol
"_" is used to represent an actual space that you must type.
Many of the macro definitions in this section are included in the macro
definition file EXAMPLES.VDF, which can be loaded with AltU. (For details,
see DEFAULT FUNCTION KEYS in VINST.REF.)
SIMPLE MACRO EXAMPLES
1. At its simplest, a function key is a way to reproduce keystrokes.
Thus, if you're writing a document that will refer to "World Wide Widgets
Ltd. (N.A.)" dozens of times, it will be easier (and cause fewer typos) if
you define this phrase as a macro and assign it to a function key like [F3].
2. The macro repeat count is an easy way to repeat VDE commands. Suppose
you have a horizontal bar installed as graphic character "Y", and you need to
enter a line of 70 of them. You could press AltG, then Y, 70 times... or you
could define the macro: AltG Y
and then Use it with a repeat count of 70.
Similarly, to reformat an entire file, go to the top if necessary, then
use a macro to repeat the reformat command ^B: just end with ^[Enter] to
proceed visibly, or go on to specify Quiet and indefinite repeat ("Q,*") for
the fastest operation (it will stop at the end of the file).
3. To view a file by scrolling slowly through it, use the macro:
Esc; ^Z or Esc; ^C
This pauses, then scrolls down (a line at a time with ^Z, a screen at a time
with ^C). Don't make it Quiet, just repeat indefinitely (with ^[Enter] or a
count of "*"); it will terminate when ^C reaches the end of the file, or when
you press [Esc].
4. This macro, with repeat count "*", would take all phrases in square
brackets "[]" found in a file, and make a list of them in a second file being
edited concurrently:
^QR ^QF[^[Enter] ^G ^KB ^QF]^[Enter] ^G ^KK AltC AltN AltP [Enter] AltB
SIMPLE FUNCTION KEY EXAMPLES
1. This macro, which could be stored as No-repeat on a function key, re-
loads the current file, eliminating any changes made since it was last saved:
^KL ^F [Enter]
2. A function key defined as ^QR ^N AltD ^OF would place the current date
at the top right of a letter. Many VDE users set up a function key to
produce a personalized letterhead: for example, the macro
^N John_Doe ^OC ^N 123_Main_St ^OC ^N City,_State ^OC
will insert that three-line address, neatly centered. You can add print
effects (bold, italic) to suit your taste. For a solid line separating this
from the body of the letter, try adding onto the end: ^N ^PS ^OF ^E ^PS ^X
3. Function keys can be used to create powerful new commands, for
example: ^D ^A ^KB ^F ^KK marks the current word as a block. And, similarly,
^QS ^KB ^X ^KK marks the current line as a block.
MACRO PROGRAMMING EXAMPLES
1. This macro moves to the start of the current paragraph, by continuing
to move back through the file until it finds a line that doesn't end with a
space (soft CR): ^QS ^S^S Esc=_[ ^D^D
Like the rest of the examples in this section, it might best be stored Quiet,
No-Repeat to a function key.
2. Moving to the start of the current sentence is a bit more complicated,
but here is a macro program to do it, with some commentary:
Esc~.1 ^S ;move left if already on period
Esc1 Esc~.< ;move left to previous period
^D Esc=_2 Esc=^M2 ;accept if followed by space or return,
^S^S Esc!1 ; otherwise ignore and continue left
Esc2 ^D Esc=_2 Esc=^M2 ;move right over any space/returns
; to start of sentence
3. If you want to produce a "pure ASCII" file for software that can't
accept control codes (other than CR,LF) or IBM graphics, here is a macro that
will filter these out before you save to disk (use file modes /A,U,N):
Esc*f ^QR ;formatting off, go to top of file
EscB Esc>~X ;delete anything above "~" (graphics)
Esc=^MN ;accept CRLF
Esc<_X ;but delete anything below " " (ctrls)
EscN ^D Esc!B ;(accept)
EscX ^G Esc!B ;(delete)
The macro will terminate when it attempts to move beyond the end of the file.
4. Here is a macro that will eliminate unwanted blank lines from a file;
every sequence of up to 10 blank lines will be reduced to just one, by
repeated use of find/replace:
Esc$$ Esc(10) Esc1 ^QA ^M^M^M [Enter] ^M^M [Enter] GN [Enter] Esc-] Esc!1
5. This macro moves the cursor to the center of the current line, using
the counter variable to figure the line length, then move back only halfway:
^QS Esc(0) ;start at left, zero counter
Esc1 Esc+ ^D ;loop: move right, increment counter
Esc~^M1 ; (until you come to the CRLF)
Esc2 Esc-] Esc-] ^S ;loop: move left, decrementing count TWICE
Esc!2 ; (macro ends when it goes to zero)
6. This macro counts and reports how many times the word at the cursor
occurs in the file:
Esc1 ^S Esc>@< ;move left to beginning of word
Esc='1 Esc=-1 ; (across letters or apostrophe/dash)
^D^KB Esc<A] ;mark start, quit if not letter
Esc2 ^D Esc>@> ;move right to end of word
Esc='2 Esc=-2 ^KK ; and mark it as block
Note that you can stop here, and you have a macro that simply marks the word
at the cursor as a block. But we continue:
Esc(0) ;zero counter
^QF^[ [Enter]GCW[Enter] ;find string (error if not found at all)
Esc$E Esc3 Esc+ ^L Esc!3 ;count and find each occurrence
EscE ^QB^KH Esc(H) ;return to word, unmark, and report count
^[ brings the marked word into the ^QF prompt; Esc(H) shows the count in the
header when finished (don't run this Quiet, or you won't see it).
7. Many programming languages use nested sets of parentheses, for example
"{}" in C. This macro, when the cursor is placed on an open bracket "{",
will move ahead to find the closed bracket "}" that matches it:
Esc~{] Esc(0) ;must be on bracket now; zero counter
Esc1 Esc~{2 Esc+ Esc!3 ;increment for every "{" encountered
Esc2 Esc~}3 Esc-] ;decrement for every "}", quit when zero
Esc3 ^D Esc!1 ;keep moving along
8. Here is a macro program using the Esc@ function (see SORTING below) in
a very simple algorithm to arrange the lines of a file in alphabetical order
by their first characters:
^QC^QS^E ;start on last line of file
Esc1 Esc$E ^QS^E^KB ;main loop: set error jump for cleanup,
^QS^X^KK Esc$3 ; mark previous line
Esc2 Esc@3 ^QS^X Esc!2 ;sort loop: find its place
Esc3 ^KV ^QP Esc!1 ;put it there, return to its position
EscE ^KH ;done, remove markers
This is reasonably fast when stored Quiet to a function key. Different
approaches could have been taken here; this macro works by building its
sorted list from the bottom of the file up (to run faster if the file is
already partially ordered). The Esc@ test is applied repeatedly to find
where each new line goes; ^QP returns to the top of the sorted section, to
continue. Esc$3 ensures that if the ^X hits the end of the text, the macro
won't terminate but the line will just be put there. Esc$E ensures that when
the ^E hits the top of the text, the macro cleans up and exits gracefully.
You can use block zoom (^KZ) to sort only a portion of a file, or
experiment with variations on this macro to sort in reverse order; on fields
other than column 1; with multiline records; etc.
---------------------- G. ADDING FEATURES: MAIL MERGE -----------------------
Many extra features commonly included in larger word processing packages
aren't built into VDE. But as the above examples have shown, macro
programming and function keys actually allow you to develop your own custom
editor commands, using the existing ones as building blocks. This means that
with macros you can often add features you need yourself, and moreover design
them to work exactly the way you want!
To demonstrate that this isn't really difficult at all, consider "Mail
Merge": the automatic production of multiple copies of the same document,
with occasional insertions at certain points taken from a data list. The
classic example is a form letter to be sent to dozens, or hundreds, of
recipients on a mailing list. Suppose we compose the text of our letter --
except that in place of a name (since they'll vary) we'll just type a
variable name, say "@@N", instead, and in place of an address, the variable
"@@A". So the file might begin:
29 February 1993
@@N
@@A
Dear @@N,
We are pleased to announce the opening of...
And in another file we have our mailing list, possibly typed by hand, more
likely generated by a database program. Various formats are possible; let's
suppose that each "entry" is a name and address, of varying numbers of lines,
terminated by an empty line. So the file might begin:
C.J. Aubergine <- first line of file
221-A Slumgullion Road
Hoagie, IL 63213
<- blank line after each entry
Margarita Empanada
P.O. Box 3172
Sopapilla, CA 91306
Karl Hasenpfeffer
Schlagsahnestr. 11
D-1380 Rotkohl
GERMANY
You'd like to have a key like [F12] programmed so that you could just
press it in order to print off a whole series of letters, one for each entry
in the list, with the appropriate information in the header and salutation.
You can probably see how you'd go about the job yourself manually, though it
would be incredibly tedious: find each "@@" variable in the letter file,
switch to the data list, mark and cut the name (for @@N) or address (for
@@N), paste it into the letter file in place of the variable name, print the
letter when done, then start all over again with the second name... Thus,
one approach to creating a mail-merge macro would be to switch on macro
recording while creating the first letter to print yourself -- ending your
recorded key sequence by reloading the original letter with the variable
names and advancing to the second entry in the list, ready to continue. Then
you could store the resulting macro to a key, and execute it repeatedly.
Alternatively, you could plan everything out ahead of time and design a
macro program containing appropriate labels and jumps to execute the entire
process automatically. The following macro will work properly with files as
described above; just install it (No-repeat) on a function key. Brief
comments have been added for explanation. Before using the macro as
presented here, you must be editing the letter file (which must have been
saved to disk), with the address list loaded as a second file, and the cursor
must be at the top of both files. If you want to test it out without wasting
paper, use a spooler utility to redirect your printer output to a disk file,
or substitute Esc; or Esc? for the ^KP[Enter] command so you can view each
version of the letter on screen as it's finished. It's rather striking how
much can be accomplished with such a modest macro.
Esc$3 ^QF@@^[Enter] ;Find next variable, skip to print if none
Esc$$ ^D^D Esc=A1 Esc~N[ ;Was it @@A or @@N? (skip if neither)
AltN ^KB^QD^KK AltC ;Request was for Name,
^QS AltN Esc!2 ; so mark and cut first line of entry
Esc1 ; (always leaving cursor at start of entry)
AltN ^X^KB^QF^M^M^[Enter] ^KK ;Request was for Address,
AltC ^QB^E AltN ; so mark and cut the rest of the entry
Esc2
^A^G^G^G ;Back to the letter: delete variable name,
AltP Esc![ ; paste in the data, and go on to next
Esc3
^KP[Enter] ;Letter is ready, so print it
^KL^F[Enter] ; and reload original copy with @@ variables
AltN ^QF^M^M^[Enter] ^D^D ;Position to next entry in list
Esc<_] ;Quit if no more entries,
AltN Esc![ ; otherwise do it all over again
You will find this macro program available for use in the EXAMPLES.VDF
file (see DEFAULT FUNCTION KEYS in VINST.REF). This example has been kept
very simple, to illustrate the basic approach; as an exercise, you might try
modifying it to put only the first name in the letter salutation, or to use
database lists in comma-delimited format, and so on. You can tailor your own
mail-merge feature to suit your requirements.
========================== 10. MACRO REFERENCE ============================
AUTOEXEC MACRO - VINST can designate one function key definition you create
as "autoexec", meaning that this macro will execute automatically whenever
you first enter VDE. This feature can be used in a variety of ways, for
example:
(1) You can use an autoexec macro to change defaults
not available as VINST options. (If you load multiple
files, remember that some settings like margins are
specific to each file, so only the first file will be
affected.)
(2) You can turn VDE into a text modification engine
by setting up a key definition (.VDF) file containing an
autoexec macro program that alters the text in some way and
then exits. (Any .VDF file specified with a ";" on the
command line is loaded before the autoexec process.)
See also SYNTAX, FUNCTION KEYS, DATA FILES. (Note: if an autoexec macro
exists, you cannot use a utility that stuffs input into the DOS keyboard
buffer before running VDE.)
CHAINING AND CALLING (Esc&,&&) - Esc&, followed by a key identification like
"!F1", is used to "chain" (or jump) to another function key. Use "!,^,@"
for Shift, Ctrl, Alt; and after the "F", a single digit "1"-"9", or "A"-
"C" for 10-12. ("0" is also accepted for F10.) Examples: Esc&F2 chains
to F2; Esc&^FB chains to Ctrl-F11.
Esc&& works similarly but "calls" the other key, returning when it
finishes. Calls may be nested at most 4 deep.
COUNTER VARIABLE (Esc(),+,-) - Esc(n) sets the counter value to "n". Esc+
simply increments the value; Esc- (minus) is a conditional jump, decre-
menting the counter, then jumping if it's zero to a specified label.
(Besides a label 0-Z, you can use "[" or "]" for the start or end, or "@"
to decrement without jumping at all.)
The counter can effectively run "negative", though it's actually an
unsigned integer: if you decrement it from 0, it becomes 65535 then 65534
(for -1, -2); if you increment it from 65535, it becomes 0. It is not
reset after a macro runs, and can be passed to another macro later.
Two special commands can also be used with the counter value:
Esc(T) - write counter value into Text at cursor position
Esc(H) - display counter value briefly in Header
DEFINE OR RECORD MACRO (^M,^M^M) - To define a macro, press ^M. You will be
asked for the macro definition; for full instructions, see DEFINING
MACROS. You can end with ^[Enter] to repeat the macro immediately, or
[Enter] to proceed to choose whether to Use the macro or to store it to an
F-key, and how.
Even if you didn't store your last macro when you originally defined
it, you can still edit, re-use or store it subsequently by using ^R
(replay) at the ^M prompt.
As an alternative to composing macros and using the ^M command to
type them in, you can simply record a macro as you go about a task. Press
^M TWICE (that is, a second time at the Macro prompt) to activate
recording; type away; then press ^M again to conclude. While recording, a
quote mark (") will be visible in the upper right (prefix) area of the
header. If you make an error while recording, use ^M to stop recording,
press [Esc] at the resulting prompt to quit, and start over.
ERROR HANDLING (Esc$) - Esc$ can specify a label where macro execution
should continue if an error occurs (normally, execution would terminate).
Thus, after the command Esc$E, any command resulting in an error (like
"Not Found") will cause a jump to label E, ignoring the error. You can
also use the special characters "[","]" to jump to the beginning or end of
the macro, or "@" to simply ignore errors, not jumping anywhere, or "$" to
return to the normal default of halting on any error.
FUNCTION KEYS ([F1]...[F12], EscA-Z,0-9) - Macros can be assigned to
function keys, either alone or with Shift, Ctrl, or Alt (!,^,@) for a
total of 48 function keys. These keys can be labeled for easy remembering
(see FUNCTION KEY LABELS), or you can assign a letter or digit to invoke a
definition with the [Esc] key; thus, if your Address is on ^[F3], you
could also call it up with (say) EscA. For detailed instructions, see
ASSIGNING MACROS TO KEYS.
(Note: users of VDE prior to version 1.7 will recall EscA-Z as a
separately definable set of macro keys; they now function simply as
mnemonic aliases for function keys.)
FUNCTION KEY LABELS (^OU) - To help you remember the purpose of your
function key definitions, the ^OU command toggles the display of a label
line at the bottom of the screen. When a key is defined, its number
appears on the label line, followed by the label (if any) entered when the
key was stored.
The label display is sensitive to keyboard shift status; if you press
and hold Shift, Ctrl, or Alt for a moment, the labels will change to show
those for the shifted function keys.
On 80-column screens, 10 labels are visible; in 40-column mode, 5.
Labels for the [F11-12] keys only appear on screens of 96 or more columns.
KEY DEFINITION FILES (AltU) - These files save function key definitions and
labels, and should be given a file type of ".VDF". You can load such a
file, along with your text file(s) to edit, from the command line (see
SYNTAX). You can also load or save .VDF files with the AltU command while
editing (see DATA FILES).
[VINST can also create .VDF files or install them in your copy of
VDE, and handle individual .VDK files; see DEFAULT FUNCTION KEYS.]
LABELS AND JUMPS (Esc0..Z,Esc!) - Esc0..Z, when placed in a macro, function
simply as local "labels" 0..Z. They have no effect, but can be "jumped"
to by other commands.
Esc! followed by 0..9,A..Z is a "jump" instruction, causing macro
execution to resume with the command following that label: for example,
Esc!2 jumps to label 2 (Esc2). As special cases, Esc![ jumps to the
beginning of the macro, and Esc!] jumps to the end (exits).
Note that labels can also be referenced by the test commands, which
perform conditional jumps (see TESTS AND LOOPS).
PAUSE OR USER INPUT (Esc;,Esc?,Esc:) - Esc; gives a brief pause before macro
execution continues, so the user can see what's happening on screen. Use
two or more to get a longer pause.
Esc? accepts text or commands from the keyboard during macro
execution. The header's "!" flag turns into "?" when user input is
expected. Anything except macro and function key commands may be used.
[Esc] terminates input, returning control to the macro. ^[Break] aborts.
Esc: makes the following command take its input from the keyboard.
The macro resumes when that command is completed. Examples: Esc:^QF
allows you to type in the string to find; Esc:Esc! actually lets you type
the label to jump to.
PROMPT AUTOMATION (^F,^[,^R) - It's worth pointing out the usefulness of
several of the control codes that operate at command prompts (see PROMPTS)
for automating operation in macros. ^F allows you to reference the
current filename in VDE file commands, or even DOS commands run from AltR.
^[ provides the current block text as prompt input, allowing the use of
commands like find/replace on whatever is there. ^R replays whatever the
previous input to this type of command (file, search, macro, etc) was.
SORTING (Esc@) - Esc@ is a essentially version of Esc< for entire strings,
rather than individual characters: it performs a string comparison (with
conditional jump) between text in a marked block and text at the cursor.
As with Esc<, the comparison goes by ASCII values, essentially
alphabetically; it proceeds character by character until a difference is
found. If the block string has a value less than or equal to the cursor
string, which is to say that it could belong "at" (@) the cursor location,
the jump is performed (possibly to code that will put it there); if
greater, not (and one might move on down the list).
NOTES: Esc@ scans up to 24 characters, is case-insensitive, and
treats accented letters in the ASCII 80-A5 range as their ordinary letter
equivalents.
Rather than having one specific sorting command built into VDE, the
Esc@ comparison can be used to implement any sorting method you require.
For example, the macro program described under EXAMPLES above does the
most common task, arranging the lines of a file alphabetically by their
initial characters. Many other variations can be imagined: reverse sort,
sort on other fields, sort records of several lines, algorithms that might
be faster in certain situations, etc.
TESTS AND LOOPS (Esc=,~,<,>) - Esc= and Esc~ perform tests on the character
at the current cursor position. They can be used in two ways:
(1) Followed by a character, then a label (0-Z,[,]),
they are conditional jumps: they jump to the label IF the
cursor character does (or for "~", does NOT) match the one
specified.
(2) Followed by a character, then ">" or "<", they are
search loops. They will continue to move the cursor right
or left as long as the cursor character does (or for "~",
does NOT) match.
Similarly, Esc< and Esc> test the cursor character's ASCII value and act
according to whether it's less, or greater, than the specified value.
(See ASCII table in VINST.REF)
(Note: place and block markers, since they aren't text characters at
all, will fail any test. If you need to check for their presence, you can
use Esc<^@ [that's 00 hex, entered as ^P@] since no actual character could
be <0 and fail this test.)
TOGGLE CONTROL (Esc*) - "Toggle" commands can create difficulties when used
in macro and function keys: ^V, for example, toggles insert mode. But
when you plan a function key, you don't necessarily know how Insert will
be set when the key is used! So if you use ^V in the macro, you don't
know whether you just turned it off or on; you might be overstriking or
inserting, and can't tell.
The Esc* command provides a solution, by letting a macro specify an
exact state for each toggle. Esc* must be followed by a LETTER to
identify a toggle, UPPERcase to turn it ON or LOWERcase to turn it OFF.
(A few options have a third state, as well.) For example, Esc*i will set
INSERT OFF, regardless of its previous state. The toggles are:
Autoindent (^OA) 'a'=off 'A'=on
Column block (^KN,I) 'c'=off 'C'=on 'O'=replace
Doublespace (^OS) 'd'=off 'D'=on
auto Format (^OM) 'f'=off 'F'=on
Hyphenation (^OH) 'h'=off 'H'=on
Insert (^V) 'i'=off 'I'=on 'W'=word
Justification (^OJ) 'j'=off 'J'=on 'R'=remove
* Load excluded files 'l'=off 'L'=on
* Match hard CRs exactly 'm'=off 'M'=on
Proportional (^OK) 'p'=off 'P'=on
* Single line reformat 's'=off 'S'=on
* Trim spaces from nondocs 't'=off 'T'=on
* Unload speller from memory 'u,U'
Variable tabs (^OV) 'v'=off 'V'=on
margin release (^OX) 'x'=off 'X'=on
hard reformat (^OY) 'y'=off 'Y'=on
The cases marked "*" actually don't correspond to standard user commands;
instead, they give access to some more of VDE's internal settings and
defaults. (Usage is described in the appropriate section of VDE.REF)
VALUE ADJUSTMENT (Esc/) - It can be very useful for a macro to adjust a
value without having to know what it previously was: to indent both
margins 10 columns, for example, whatever they were. The Esc/ command
makes this possible: it must be followed by a LETTER to identify the
value, a NUMBER from 1 to 99, and finally a "+" or "-" sign. The
adjustments are:
Left margin (^OL) 'L'
Right margin (^OR) 'R'
Page length (^OP) 'P'
Example: Esc/L10+ increases the left margin by 10 columns. Like the Esc*
toggles, these commands are primarily intended for, but not limited to,
use in macros.
=============================[end VMACRO.REF]================================